
\documentclass{article}

\usepackage{amssymb}
\usepackage{nicefrac}
\usepackage{alltt}
\usepackage{comment}


\begin{document}
\author{Stephen Peter Tetley}
\title{Mullein User Guide}
\maketitle
\tableofcontents

\section{Introduction}
\subsection{What is Mullein?}
Mullein is set of modules for music description language written 
in Haskell. Mullein is primarily inspired by Paul Hudak's 
Haskore system, but Mullein has a different objective to Haskore: 
Mullein describes musical structures for rendering as printed 
scores; Haskore describes musical structures for 
\emph{performance}, where a performance is typically rendered to 
a sound file. 

Ideally Mullein would not be a separate system to Haskore, but
an extension allowing Haskore to generate scores as well 
as performances. Unfortunately Haskore with its emphasis on 
performance is not well suited to describing scores. Valuable
musical information for score printing is not readily available
in Haskore. The most obvious example is duration - Haskore 
records note durations as absolute values, in printed scores 
durations are symbolic (a eighth note always has the same 
symbolic duration \nicefrac{1}{8} regardless of the tempo 
of the music). While is easy to recover note durations from 
simple Haskore performances it is very difficult to recover 
durations in if a score has trills or other ornaments.

An early prototype of Mullein tried to alleviate this problem 
by allowing Haskore performances to be augmented with rewriting 
rules to recover symbolic durations from absolute ones. But the 
additional machinery was excessive and hardly intuitive, 
strongly suggesting that abandoning compatibility with Haskore
was best option for Mullein.

\begin{comment}

unit note length

pitch relative to scale 

Mullein represents durations symbolically... 
\begin{alltt} 
longa, breve, \nicefrac{1}{1}, \nicefrac{1}{2}, \nicefrac{1}{4},
\nicefrac{1}{8}, \nicefrac{1}{16}
\end{alltt}
\end{comment}




\section{Micro guide to LilyPond}
LilyPond is a comprehensive music typesetting system. The name 
LilyPond is synonymous with both the system and the music 
description format (prosaically \emph{LilyPond files}).
Presentation is impeccably flexible, with it one can produce 
simple tunes, orchestral scores, string tablature, even MIDI. Of 
course, it can seem bewildering when first encountered, 
especially if one is unfamiliar with is forebear \TeX.

Presentation - the details of how to structure scores, systems - 
is too various to be covered succinctly here. These notes cover 
only details relevant to the fragments that Mullein can output.

Two fortuitous details beforehand: LilyPond allows musical 
fragments to be named as variables then referred to elsewhere,
secondly, scores can be divided amongst files and included in a
master file with the \verb+\include+ command. These features are 
invaluable for working with Mullein - volatile, generated 
fragments can be isolated in their own files, minimizing the 
chances of overwriting carefully handwritten document masters.
 
\subsection{Pitch}
Middle C is represented by the symbol \verb+c'+. All pitches 
are spelled with lowercase letters. Altered pitches must 
be spelled with their accidental whether or not the accidental 
will be printed according to the key signature. In G major
\verb+f+ will be printed as F$\natural$, \verb+fis+ will be
printed as F. LilyPond uses Dutch suffixes for sharp 
(\verb+is+) and flat (\verb+es+), it can be configured to use
English or another language, but convention prefers Dutch.

Octaves are raised with one-or-more apostrophes and lowered 
with one-or-more commas. For example, \verb+c''+ is C one octave 
above middle C, \verb+c+ is C one octave below middle C and 
\verb+c,+ is C two octaves below middle C. A side issue, why 
LilyPond doesn't represent middle C as \verb+c+ is somewhat 
mysterious.

LilyPond has two modes for representing octave information - 
relative and absolute - with relative mode appearing to be most 
popular for score authors. Relative mode allows slightly more 
concise scores, as octave annotations are only needed when the 
staff spacing between two successive notes is greater than three 
in either direction (accidentals are ignored in the calculation).

\subsection{Duration}
Durations are denoted by numerals following the notes pitch:
\verb+c'1+ represents a whole note, \verb+c'2+ a half note, 
\verb+c'4+ a quarter note, etc. Dotted notes are made by placing 
a dot after the numeral (\verb+c'4.+). To improve concision, 
when a series of notes shares the same duration only the first 
needs annotation. For instance, four eighth notes followed by a 
quarter note - \verb+d'8 e d c c4+. Dotted notes are an exception 
to this rule: all dotted notes must be specified regardless of
what they succeed.

\subsection{Metrical division: Beaming and bar lines}
LilyPond will beam note groups automatically according to the 
time signature. As there are often various rhythmic divisions 
possible for a time signature this is not always ideal. Notes 
can be beamed manually by grouping them within square brackets 
(\verb+[]+).

Scores can elide bar lines, LilyPond will place them 
automatically. Automatic bar lines can be overrode - LilyPond 
will report a warning to the console during rendering if the 
duration of the bar does not agree with the time signature.


\section{Micro guide to ABC}
ABC is a music notation format. Various tools exist to turn ABC 
files into something useful - PostScript scores, MIDI. 
\verb+abc2ps+ and \verb+abcm2ps+ both convert ABC to PostScript, 
\verb+abcm2ps+ is a later system an supports some very useful 
features from the ABC 2.0 draft standard (particularly voice 
overlays). 

ABC files define tunes or their collective \emph{tune-books}. ABC 
does not attempt to match LilyPond's utility, one could not 
prepare an orchestral score in ABC. Tunes have a simple prologue
defining title, key signature, meter etc. and then a tune body
listing the notes. Due to the modest scale of ABC, generating a
whole file programmatically is not unreasonable.\footnote{In 
contrast LilyPond is simply to large to usefully embed it 
Haskell. It is more fruitful to generate fragments in Haskell 
and assemble them with handwritten LilyPond in a master document, 
one can then use whatever LilyPond commands one wishes.} Indeed, 
as the include file mechanisms of ABC are somewhat limited whole 
file generation should probably be preferred.

\subsection{Pitch}
Middle C is represented by the symbol \verb+C+.
The two octaves spanning the treble clef are represented
with the pitches \verb+C-Bc-b+. Pitches outside this range are 
formed by appending commas or apostrophes. Each comma appended 
lowers the octave, e.g. \verb+C,,+ is c two octaves below middle 
C. Similarly appending apostrophes raises the octave \verb+c'+ 
is one octave above \verb+c+ (and two octaves above middle C). 
ABC allows equivalent octave spellings, although the merit of 
this in practice is questionable. These alternatives all denote 
middle C: \verb+C  c,  C,'  c,,'  c,',+

ABC tunes have a key signature defined in the header prologue 
(if the key signature is not specified it defaults to C major).
With this context established, notes only need to be augmented 
with accidentals if the accidental needs printing. For instance, 
in G major the note \verb+F+ in the score represents the 
absolute pitch F$\sharp$, but following notational conventions 
the sharp is elided, a musician knows to play it as 
F$\sharp$ from the key signature. In G major, \verb+=F+ prints 
F$\natural$ and \verb+^F+ prints F$\sharp$, decorating the F 
with a cautionary (though strictly superfluous) sharp. 

\subsection{Duration}
Durations in ABC tunes are denoted by multipliers of the 
\emph{unit note length} rather than absolute values. This is a 
shorthand to reduce typing, no annotation is needed to notes 
whose duration equals the unit note length. A note G with 
duration double the unit note length is \verb+G2+, with duration 
half the unit note length it is \verb+G/2+.

The unit note length is either specified in the header of the 
tune, or derived from the meter. The derivation is: 
if the meter expressed as a decimal is $\geqq$ 0.75 then the 
unit note length is an eighth, otherwise it is a sixteenth.

\subsection{Metrical division: Beaming and bar lines}
Notes to be joined within a beam group must be grouped together
without spaces, which makes the ABC format white space sensitive!
ABC is permissive in its interpretation of a beam group: if the 
group includes a note that cannot be beamed (say a quarter or half
note) it will be printed singularly and the beam group will be 
resumed. The flip side of this flexibility with beam groups is a
score is free to designate beam groups that have no correlation  
with the pulsation implied by a tune's meter.

Barring is entirely at the mercy of the user. Bars are be printed 
where they are placed, neither \verb+abc2ps+ or \verb+abcm2ps+ 
appear to give warnings when bars are too long or too short for 
the meter.


\end{document}
